home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr44 / xlib50.zip / README.DOC < prev    next >
Text File  |  1995-03-10  |  24KB  |  478 lines
  1. File Dated:  03/10/95
  2.  
  3. ******************************************************************************
  4. Quick Start with XLIB
  5. ******************************************************************************
  6.  
  7.    The user manual is largely dedicated to cover specifics of XLIB which 
  8. will not be of concern to many programmers.  A few notes are added here to
  9. expedite matters for these programmers.
  10.    If you are not an assembly language programmer, then consider using 
  11. EASYX rather than XLIB.  EASYX does not require use or knowledge of 
  12. assembly language.  The documentation for EASYX is in the file EASYX.DOC.
  13.    If you are familiar with assembly language, then start by reading the 
  14. file DONTREAD.ME.  This file is for those who don't particularly enjoy 
  15. reading 60 page user manuals.  It is an excellent tutorial.  You will 
  16. probably be ready to program with XLIB after working through the tutorial.
  17.    If your program is to be written exclusively in assembly language, then
  18. examine the files FLAT.INC and FLAT.ASM.  FLAT.INC is an include file which
  19. enables flat-model programming in DOS.  FLAT.ASM illustrates usage of
  20. FLAT.INC.
  21.  
  22. ******************************************************************************
  23. Frequently Encountered Problems When Starting XLIB
  24. ******************************************************************************
  25.  
  26.    The most frequently reported problem with XLIB is in fact no problem at
  27. all.  XLIB presents a registration reminder message when terminating.  Some 
  28. interpret this message as meaning that the shareware version of XLIB is 
  29. disabled.  This is not the case.  The shareware version is fully 
  30. functional.  You must register XLIB to obtain a copy of the library that 
  31. does not present the message.
  32.    The registration reminder message is actually a confirmation that XLIB
  33. has been initiated and terminated successfully.  If this message doesn't 
  34. appear in the shareware version, then the main program almost certainly has
  35. a bug preventing clean termination.
  36.    The second most frequently reported problem is by assembly language
  37. programmers who find that attempts to initialize XLIB (with INITXLIB) fail
  38. for lack of DOS memory.  MASM programmers must remember to link with the
  39. CPARM:1 parameter.  TASM programmers must resize the memory block into
  40. which DOS loaded the program (see EXAMP1B.ASM).
  41.  
  42. ******************************************************************************
  43. Registering XLIB
  44. ******************************************************************************
  45.  
  46.    XLIB may be registered for $50.  Registrants will be sent a registered
  47. copy of the XLIB archive along with a printed copy of the user manual.
  48. Technical support is provided for both registered and unregistered users;
  49. however, if you have used technical support or intend to use it, then the
  50. registration fee is $70.
  51.  
  52. There are four ways to register XLIB.  We prefer that you use one of the
  53. first two methods:
  54.  
  55. 1) By email using MasterCard or Visa:
  56.  
  57.    Edit the form in the file EMAIL.REG then email the file to TechniLib.
  58.  
  59. 2) By mail to TechniLib:
  60.  
  61.    Send check or money order along with return address to:
  62.  
  63.    TechniLib Company
  64.    P.O. Box 6818
  65.    Jackson, Ms 39282
  66.    USA
  67.  
  68.    Please write "XLIB" on check or include an explanatory note.  An email 
  69. address would also be appreciated.
  70.  
  71. 3) By credit card through Public (software) Library:
  72.  
  73.    You can order with MC, Visa, Amex, or Discover from Public (software)
  74. Library by calling 800-2424-PsL or 713-524-6394 or by FAX to 713-524-6398
  75. or by CIS email to 71355,470.  You can also mail credit card orders to PsL
  76. at P.O.Box 35705, Houston, TX 77235-5705.  The product ID for XLIB is 11077.
  77.  
  78.    THE ABOVE NUMBERS ARE FOR ORDERS ONLY.  Any questions about the status of 
  79. the shipment of the order, refunds, registration options, product details, 
  80. technical support, volume discounts, dealer pricing, site licenses, etc, 
  81. should NOT be directed to PsL.  Direct all such questions to TechniLib.
  82.  
  83. 4) Through CompuServe:
  84.    
  85.    Use GO SWREG (shareware registration).  The program identification number 
  86. is 1778.  The program title is XLIB 5.0.
  87.  
  88.  
  89.    XLIB may be registered for $50.  Registrants will be sent a registered
  90. copy of the XLIB archive along with a printed copy of the user manual.
  91. Technical support is provided for both registered and unregistered users;
  92. however, if you have used technical support or intend to use it, then the
  93. registration fee is $70.
  94.  
  95. ******************************************************************************
  96. Obtaining the Most Recent Version of XLIB
  97. ******************************************************************************
  98.  
  99.    The most recent version of XLIB may be downloaded from:
  100.  
  101. 1) CompuServe - GO MSLANG or GO BCPPDOS then choose ASSEMBLER.
  102. 2) Internet -   oak.oakland.edu under directory \pub\msdos\c
  103.  
  104.    Expect the archive to be named either XLIBvv.ZIP or DXLIBvv.ZIP where
  105. vv denotes the version number.
  106.    Keywords for XLIB include:  XMS, DPMI, VCPI, DOS, EXTENDER, PROTECTED
  107. MASM, TASM, TECHNILIB.
  108.  
  109. ******************************************************************************
  110. Improvements in XLIB Version 5.0 Over Version 4.1
  111. ******************************************************************************
  112.    
  113.    XLIB version 5.0 is a major upgrade.  Changes include:
  114.  
  115. 1) Interrupt handlers for INT 23H (CTRL C) and INT 24H (DOS Critical Error)
  116.    are included in version 5.0.  In earlier version, termination under 
  117.    either of these interrupts left the machine in an unstable state.  
  118. 2) The FPU interrupt handler has been improved.  It now optionally presents 
  119.    a report of the FPU exception which includes the cause and location of 
  120.    the exception.
  121. 4) Version 5.0 contains new procedures for handling uncommitted memory.  
  122.    This is a very useful feature, but requires DPMI 1.0 (see below).
  123. 5) Earlier version of PMIO did not properly handle rounding in some very
  124.    rare cases.  A number such as 5.999999999 could have been printed as 5.0.
  125.    The new version of PMIO.INC does not assume that DS contains a flat-model 
  126.    selector.  PMIO may therefore be used with any segment settings.  Also
  127.    PMIO contains numerous additional procedures.  Those presently using PMIO
  128.    should consult the comments in this file before using the new version.
  129. 6) The archive for version 5.0 contains a new include file called FLAT.INC
  130.    This file enables flat-model programming under DOS.  The file is 
  131.    thoroughly documented.  FLAT.ASM illustrates usage of FLAT.INC.
  132. 7) Example files for TASM programmers have been modified to use the FARSTACK
  133.    option on the .MODEL statement.  See the discussion below about bugs
  134.    in compilers etc. for an explanation of this change.
  135. 8) Extensive changes have been made to documentation.
  136. 9) The availability of a protected-mode debugger is announced.  See the file
  137.    SWAT.DOC for details.
  138.  
  139. ******************************************************************************
  140. Communicating with TechniLib Via Electronic Mail
  141. ******************************************************************************
  142.  
  143.    You can communicate with TechniLib via CompuServe or Internet electronic 
  144. mail.  Direct CompuServe mail to user ID: 74730,167.  Internet users should
  145. use the address: 74730.167@compuserve.com.  Internet users may also send
  146. mail to davidpyles@delphi.com.
  147.  
  148. ******************************************************************************
  149. Instructions for Constructing Protected-Mode Libraries for Microsoft
  150. ******************************************************************************
  151.  
  152.    The following batch file uses Microsoft LIB to combine an OBJ file with
  153. XLIB.LIB to produce a protected-mode library.  Call the batch file using the
  154. base name of the OBJ file as the argument.  This base name will also be 
  155. given to the library.  It is assumed that the OBJ file and XLIB.LIB are in 
  156. the current directory.  LIB.EXE is assumed to be in the ..\BIN directory.
  157.  
  158. @echo on
  159. del %1.lib
  160. ..\bin\lib %1.lib /noi +%1.obj+xlib.lib;
  161.  
  162.    The following batch file uses Microsoft LINK and LIB to combine an OBJ
  163. file with XLIB.LIB to produce a protected-mode library and quick library for
  164. Microsoft BASIC 7.0.  Call the batch file using the base name of the OBJ
  165. file as the argument.  This base name will also be given to the library and
  166. the quick library.  It is assumed that all files apart from LINK.EXE and
  167. LIB.EXE are in the current directory.  The current directory must also
  168. contain the file QBXQLB.LIB (included in the BASIC distribution disks).
  169. LINK.EXE and LIB.EXE are assumed to be in the ..\BIN directory.
  170.  
  171. @echo on
  172. del %1.qlb
  173. del %1.lib
  174. ..\bin\link /q/nopackf xlib.lib+%1.obj,%1.qlb,,qbxqlb.lib;
  175. ..\bin\lib %1.lib +xlib.lib+%1.obj;
  176.  
  177.    The following command may be used to create a quick library from 
  178. EASYX.LIB.  The quick library is called EASYX.QLB:
  179.  
  180. ..\bin\link /q/nopackf easyx.lib,easyx.qlb,,qbxqlb.lib;
  181.  
  182. ******************************************************************************
  183. Instructions for Constructing Libraries and Linking with Borland
  184. ******************************************************************************
  185.    
  186.    The following batch file uses TLINK to link an OBJ file from TASM with
  187. XLIBB.LIB to produce a DOS-extended executable.  The base name of the OBJ
  188. is supplied as an argument to the batch file.  The executable will be given 
  189. the same base name as the OBJ file.  It is assumed that the OBJ file is in 
  190. the current directory and that TLINK is in the ..\BIN directory.
  191.  
  192. @echo on
  193. ..\bin\tlink /3/c %1.obj,,,xlibb.lib
  194.  
  195.    The following batch file uses Borland TLIB to combine an OBJ file with
  196. XLIBB.LIB to produce a protected-mode library.  Call the batch file using 
  197. the base name of the OBJ file as the argument.  This base name will also be 
  198. given to the library.  It is assumed that XLIBB.LIB and the OBJ file are in 
  199. the current directory.  TLIB is assumed to be in the ..\BIN directory.
  200.  
  201. @echo on
  202. del %1.lib
  203. ..\bin\tlib /C %1.lib +xlibb.lib+%1.obj
  204.  
  205.    Borland C and Turbo C users can compile within the IDE; however, they 
  206. must use the command line linker because an option will be needed which is 
  207. not included in the IDE linker.  In particular, the /3 option will be needed 
  208. to enable processing of 32-bit segments.  The appropriate commands to TLINK 
  209. will depend upon the memory model being used.  The following batch command 
  210. will link a program called MYPROG with a library call MYLIB under the large 
  211. memory model.  The batch command must be issued from the directory 
  212. containing MYPROG.OBJ.  It is assumed that TLINK is in the ..\BIN directory 
  213. and that MYLIB.LIB is in the ..\LIB directory.  It is also assumed that all 
  214. of the C link libraries are in the ..\LIB directory.  The resulting 
  215. executable will be called MYPROG.EXE and the map file will be called 
  216. MYPROG.MAP.  The command line is lengthy and is therefore broken into two 
  217. lines below.
  218.  
  219.                            --------------------- model specification
  220.                            .   ----------------- obj file name
  221.                            .   |      ---------- exe file name
  222.                            .   |      |      --- map file name
  223.                            . ______ ______ ______
  224. ..\bin\tlink /3/c ..\lib\c0l myprog,myprog,myprog,
  225.  
  226.    ..\lib\mylib ..\lib\fp87 ..\lib\mathl ..\lib\cl 
  227.           -----                        .         .
  228.             |                          -------------- model specification
  229.             ----------------------------------------- lib file name
  230.  
  231.  
  232.    To link under the small memory model, replace "l" with "s" at the model
  233. specification characters.  Use "m" for the medium model; "c" for the compact
  234. model, and "h" for the huge model.
  235.  
  236. ******************************************************************************
  237. NOEMS and Equivalent Options
  238. ******************************************************************************
  239.  
  240.    Early versions of XLIB did not initialize properly when the NOEMS or
  241. equivalent option was being used on the memory manager.  This problem should 
  242. be corrected under version 4.1, but we suggest avoiding NOEMS.  If the upper 
  243. memory area used by the page is needed, then try FRAME=NONE or equivalent 
  244. option.
  245.    When EMS is present, VCPI has control of the machine.  This means that
  246. XLIB must work cooperatively with VCPI when performing switches to protected
  247. mode; otherwise, XLIB would cause a protection violation (exception #13).
  248. VCPI is a subset of EMS.  When NOEMS is used, it appeared to former 
  249. versions of XLIB that VCPI was absent.  The latter assumption was false, 
  250. because the memory manager was hiding VCPI behind the NOEMS option.  XLIB 
  251. then proceeded to perform uncooperative mode switches.  This then generated 
  252. the exception.  Versions 4.1 and later take measures to detect a deceptive
  253. memory manager.
  254.  
  255. ******************************************************************************
  256. General Debugging Instructions
  257. ******************************************************************************
  258.  
  259.    See the file SWAT.DOC for instructions toward obtaining a powerful
  260. protected-mode debugger.
  261.    Neither Turbo Debugger nor Codeview will be able to debug protected-mode
  262. instructions.  However, one should still be able to use the debuggers for
  263. real-mode areas of a program.  Simply step over calls to protected-mode
  264. procedures.
  265.    Some debuggers tend to have problems when XLIB is initialized for DPMI.  
  266. Use VCPI instead.  This is done by setting bit 0 of IFLAGS.  Of course, a 
  267. VCPI driver needs to be loaded.  EMM386, QEMM386, and 386MAX all have VCPI.  
  268. VCPI cannot run in Windows or OS/2.  
  269.    In the event one can debug under DPMI 1.0, then it must be remembered
  270. that XLIBE and XLIBEB attempt to trap exceptions in real mode, including
  271. debug exceptions and breakpoints.  This probably will not interfere with
  272. the debugger; however, if problems occur, these features should be disabled 
  273. by setting bit 1 of IFLAGS.  This disables all exception trapping and 
  274. prevents remap of hardware interrupts.
  275.    
  276. ******************************************************************************
  277. Instructions for Debugging in the Borland IDE
  278. ******************************************************************************
  279.  
  280.    To run the IDE debugger, XLIB should be initialized for VCPI.  However,
  281. under the default behavior of the IDE, a VCPI program will not be able to
  282. allocate extended memory within the IDE.  There are potentially two reasons 
  283. for this.  First, the default behavior of the DPMI kernel under which the 
  284. IDE operates is to claim all EMS memory and convert it to DPMI memory.  
  285. Since VCPI seeks extended memory through EMS, no extended memory will appear 
  286. to be available.  To limit the memory consumption of the DPMI kernel, 
  287. include a statement such as the following in the batch file used to invoke 
  288. the IDE:
  289.  
  290. set dpmimem=maxmem 2000
  291.  
  292. This statement limits the memory usage of the DPMI kernel to 2000Kb.  If
  293. EMS memory exceeds this amount, then EMS memory will be available to the 
  294. IDE.  However, EMS memory will not be available to a VCPI program running 
  295. within the IDE if the IDE has itself consumed all EMS memory.  Therefore, 
  296. one may have to limit EMS memory usage of the IDE.  This can be done in the 
  297. OPTIONS|ENVIRONMENT|STARTUP menu of the IDE.  Typically, EMS memory usage
  298. should be set to zero here.
  299.  
  300. ******************************************************************************
  301. Known Bugs/Peculiarities in Memory Managers, Operating Systems, and Compilers
  302. ******************************************************************************
  303.  
  304. QEMM and QDPMI:
  305. ---------------
  306.  
  307. 1) All versions of QDPMI appear to map physical address spaces incorrectly.
  308.    The actual mapping call will succeed; however, this call affects QDPMI
  309.    internally such that subsequent calls to allocate extended memory do not
  310.    function correctly.  This means that MAPIO and PMMAPIO will not work
  311.    reliably with QDPMI.
  312.  
  313. 2) QDPMI apparently does not function properly when the NOEMS option has 
  314.    been used on QEMM.  NOEMS typically should not be used with any memory 
  315.    manager.  If you need the space normally allocated to the EMS page frame, 
  316.    then set FRAME=NONE (or equivalent option) instead of using NOEMS.
  317.  
  318.    These problems have been reported to Quarterdeck.  Corrections are
  319. expected in the near future.
  320.  
  321. 386MAX:
  322. -------
  323.  
  324. 1) 386MAX versions 6.X and 7.0 leave interrupts disabled after calls to
  325.    certain VCPI memory management functions.  This means that when VCPI is
  326.    being used, interrupts will be disabled after calls to PMGETMEM, 
  327.    PMFREEMEM, PMRESETMEM, and PMMAPIO.
  328.  
  329. 2) 386MAX version 7.0 does not properly report the virtual debug status
  330.    register (virtual DR6) upon debug exceptions.  Consequently, the DR6
  331.    value presented by the XLIBE exception handler will not be valid.  This
  332.    version also fails to clear debug breakpoints upon termination, as 
  333.    required of DPMI 1.0 hosts.  XLIBE corrects the latter problem by 
  334.    clearing breakpoints itself when terminating.
  335.  
  336. 3) 386MAX version 7.0 apparently mismanages exception #13 from real mode.
  337.    When the XLIBE exception handler attempts to terminate after such 
  338.    exceptions, a second exception #13 occurs.  This has not proven to be a
  339.    major problem.  Simply ignore the second exception.
  340.  
  341.    386MAX version 7.01 apparently corrects all of the above problems found
  342. in version 7.0.  Qualitas has made a patch available to implement these
  343. corrections.  Download the patch from the Qualitas BBS (301-907-8030).  The
  344. patch for 386MAX is M701R.ZIP.  The patch for BlueMax is B701R.ZIP.
  345.  
  346. OS/2:
  347. -----
  348.  
  349.    OS/2 3.0 (Warp) and possibly previous versions do not preserve the high
  350. word of EDX upon certain calls to INT 21H function 3DH (open file).  XLIB
  351. version 5.0 takes corrective action on this bug.
  352.  
  353. Windows 3.1:
  354. ------------
  355.  
  356.    Windows DPMI doesn't handle INT 3 properly.  The XLIB exception handler
  357. never receives control under this interrupt under Windows.
  358.  
  359. TASM 4.0:
  360. ---------
  361.  
  362.    TASM 4.0 does not necessarily place DGROUP as the last segment if other
  363. data segments are defined after the .MODEL statement; consequently, it
  364. cannot be assumed that the stack will be located at the end of the program.
  365. This creates a problem when it becomes necessary to determine the size of
  366. a program for purposes of resizing the memory block in which DOS has placed
  367. it.  The easiest way to correct this problem is by using FARSTACK in the 
  368. .MODEL statement.  If the stack must be in DGROUP (NEARSTACK), then all
  369. data segments should be defined before .MODEL and should be given a combine
  370. type of 'FAR_DATA'.  This implies that if XLIBB or XLIBEB are to be used 
  371. with NEARSTACK, then XLIBB.INC should be placed before .MODEL.
  372.  
  373. ******************************************************************************
  374. Real-Mode Exception Trapping with DPMI Version 1.0 
  375. ******************************************************************************
  376.  
  377.    DPMI 1.0 enables XLIBE to trap exception in real mode.  This makes XLIBE
  378. potentially useful to programmers who would otherwise have no interest in
  379. protected-mode programming.  Simply place a call to INITXLIB early in your
  380. program and link with XLIBE.LIB (XLIBEB.LIB for Borland users) to implement
  381. this feature.
  382.    386MAX version 7.X is the only DPMI 1.0 host of which we are presently 
  383. aware.  Version 7.01 is an outstanding product.
  384.  
  385. ******************************************************************************
  386. Contracted Programming and Consultation
  387. ******************************************************************************
  388.  
  389.    TechniLib will perform contract programming at competitive rates.
  390. TechniLib will also serve as a consultant to other programmers.  Contact
  391. TechniLib through the channels presented above.
  392.  
  393. ******************************************************************************
  394. Improvements in XLIB Version 2.0 Over Version 1.0
  395. ******************************************************************************
  396.  
  397. 1) Procedures enabling protected-mode programming in C using inline 
  398.    assembly.
  399. 2) Protected-mode file routines which can transfer extended memory to files 
  400.    or files to extended memory.  Sequential and random access are supported.
  401. 3) Better interrupt management services.
  402. 4) User-defined descriptors.
  403. 5) More descriptors.  
  404. 6) More configurability.
  405. 7) Minor bug fixes
  406. 8) Better documentation.
  407.  
  408. ******************************************************************************
  409. Improvements in XLIB Version 3.0 Over Version 2.0
  410. ******************************************************************************
  411.  
  412. 1) Files included in Borland formats.
  413. 2) EASYX library included for those unfamiliar with assembly language.
  414. 3) MAPIO and PMMAPIO procedures added to XLIB for accessing memory-mapped 
  415.    input/output devices.
  416. 4) Better documentation
  417.  
  418. ******************************************************************************
  419. Improvements in XLIB Version 4.0 Over Version 3.0
  420. ******************************************************************************
  421.  
  422. Additions:
  423.  
  424.    The principal improvement in version 4.0 is the inclusion of libraries
  425. with exception trapping capabilities.  XLIB 4.0 can trap all protected-mode
  426. exceptions.  If DPMI 1.0 is installed, then real-mode exceptions can be
  427. trapped as well.  These libraries also contain new functions for managing
  428. debug watchpoints.
  429.    XLIB 3.0 was limited in that it did not allow the main program to spawn
  430. other processes.  This limitation has been corrected.
  431.    The global descriptor table has been made public in version 4.0.  
  432.    PMPRINT.ASM has been replaced with PMIO.INC.  The latter contains better
  433. print routines as well as new keyboard and speaker routines.  PMIO.INC is
  434. designed for either MASM or TASM.
  435.    The MOVMEM routine in EASYX has been redesigned to be faster and to be
  436. reentrant.  This routine may now be called in the main thread, in interrupt
  437. handlers, or both.
  438.    Microsoft BASIC 7.0 files have been included to illustrate usage of 
  439. EASYX.
  440.  
  441. Corrections:
  442.  
  443.    Version 4.0 corrects certain bugs and makes accommodations for anomalies
  444. in BIOS and common resident software.
  445.    The most severe bug in version 3.0 was a mistake in the include file
  446. XLIB.INC.  The combine type on segment DSEG was set to FAR_DATA, whereas it
  447. should have been DATA.
  448.    A second bug caused the machine to crash with a call to INITXLIB when
  449. certain memory managers were used with the NOEMS option.
  450.    Version 3.0 did not preserve the interrupt flag through mode switches.
  451. Instead it always enabled interrupts after the switch.  This lead to awkward
  452. situations when attempting to use SWITCHPM and SWITCHRM in interrupt 
  453. handlers.  Version 4.0 always preserves the interrupt flag through a mode 
  454. switch.
  455.    A bug prevented SWITCHPM and SWITCHRM from being reentrant under VCPI.
  456. This bug existed in both versions 3.0 and 3.1.  This would have caused a
  457. problem if nested mode switches were being performed, as would be the case
  458. with calls to DEFLECTPM or other mode switches within interrupt handlers.
  459.    Certain versions of SMARTDRV.EXE do not restore the global descriptor
  460. table register.  Version 3.0 was not prepared for this
  461.    Certain BIOS software interrupts return with interrupts enabled.  Neither
  462. version 3.0 nor version 3.1 were prepared for this anomaly.  It caused the
  463. machine to hang upon certain hardware interrupts, keypresses in particular.
  464.    The other bugs were applicable only when running XLIB in the absence of
  465. VCPI and DPMI (HIMEM.SYS only or no memory manager at all).  Accesses to
  466. extended memory failed in some cases.  In some cases the machine was left 
  467. in an unstable state.
  468.  
  469. ******************************************************************************
  470. Improvements in XLIB Version 4.1 Over Version 4.0
  471. ******************************************************************************
  472.  
  473.    Version 4.1 is minor upgrade.  The exception handler under version 4.0
  474. did not properly manage keypresses.  This problem has been corrected in
  475. version 4.1.  A minor bug has also been corrected in DONTREAD.ME.
  476.  
  477.  
  478.